package optimization.naturalOptimization.evolutionaryAlgorithm.evolutionStrategy.cma;

/*
 Copyright 2003, 2005, 2007 Nikolaus Hansen 
 e-mail: hansen .AT. bionik.tu-berlin.de
 hansen .AT. lri.fr

 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU Lesser General Public License, version 3,
 as published by the Free Software Foundation.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU Lesser General Public License for more details.

 You should have received a copy of the GNU Lesser General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.

 Last change: $Date: 2010-12-02 23:57:21 +0100 (Thu, 02 Dec 2010) $
 */

/**
 * Simple container of (mostly generic) options for the optimization, like the
 * maximum number of objective function evaluations, see class fields. No
 * explicit setting of options is needed to initialize the CMA-ES (
 * {@link CMAEvolutionStrategy#init()}) and options of the CMA-ES can be set and
 * changed any time, either via a property file and the method , or new values
 * can simply be assigned to the fields of the public <code>opts</code> field of
 * the class <code>CMAEvolutionStrategy</code> (yeah, I know, not exactly Java
 * style).
 * 
 */
public class CMAOptions implements java.io.Serializable {
	// needs to be public to make sure that a using class can excess Options.
	// Therefore, if not nested, needs to move into a separate file

	private static final long serialVersionUID = 2255162105325585121L;

	/**
	 * number of initial iterations with diagonal covariance matrix, where 1
	 * means always. Default is diagonalCovarianceMatrix=0, but this will
	 * presumably change in future. As long as
	 * iterations<=diagonalCovarianceMatrix the internal time complexity is
	 * linear in the search space dimensionality (memory requirements remain
	 * quadratic).
	 */
	public long diagonalCovarianceMatrix = 0; // -1;

	/**
	 * lower bound for standard deviations (step sizes). The Array can be of any
	 * length. The i-th entry corresponds to the i-th variable. If
	 * length&#60;dim the last entry is recycled for all remaining variables.
	 * Zero entries mean, naturally, no lower bound.
	 * <P>
	 * CAVE: there is an interference with stopTolX (and stopTolXFactor): if
	 * lowerStdDev is larger than stopTolX, the termination criterion can never
	 * be satisfied.
	 * </P>
	 * <p>
	 * Example:
	 * 
	 * <pre>
	 * CMAEvolutionStrategy es = new CMAEvolutionStrategy();
	 * es.options.lowerStandardDeviations = new double[] { 1e-4, 1e-8 }; // 1e-8 for
	 * 																	// all but
	 * 																	// first
	 * 																	// variable
	 * </pre>
	 * 
	 * @see #stopTolX
	 * @see #stopTolXFactor
	 * */
	public double[] lowerStandardDeviations;
	/**
	 * upper bound for standard deviations (step lengths). Zero entries mean no
	 * upper bound. Be aware of the interference with option stopTolUpXFactor.
	 * 
	 * @see #lowerStandardDeviations
	 * @see #stopTolUpXFactor
	 * */
	public double[] upperStandardDeviations;

	/**
	 * stop if function value drops below the target function value stopFitness.
	 * Default = <code>Double.MIN_VALUE</code>
	 */
	public double stopFitness = Double.MIN_VALUE;
	/**
	 * stop if the maximum function value difference of all iteration-best
	 * solutions of the last 10 + 30*N/lambda iterations and all solutions of
	 * the recent iteration become <= stopTolFun. Default = 1e-12.
	 * */
	public double stopTolFun = 1e-12;
	/**
	 * stop if the maximum function value difference of all iteration-best
	 * solutions of the last 10 + 30*N/lambda iterations become smaller than
	 * stopTolFunHist. Default = 1e-13. The measured objective function value
	 * differences do not include repair penalties.
	 */
	public double stopTolFunHist = 1e-13; // used if non-null
	/** stop if search steps become smaller than stopTolX. Default = 0 */
	public double stopTolX = 0.0;
	/**
	 * stop if search steps become smaller than stopTolXFactor * initial step
	 * size. Default = 1e-11.
	 */
	public double stopTolXFactor = 1e-11; // used if TolX is null
	/**
	 * stop if search steps become larger than stopTolUpXFactor * initial step
	 * size. Default = 1e3. When this termination criterion applies on a static
	 * objective function, the initial step-size was chosen far too small (or
	 * divergent behavior is observed).
	 */
	public double stopTolUpXFactor = 1e3; // multiplier for initial sigma
	/**
	 * stop if the number of objective function evaluations exceed
	 * stopMaxFunEvals
	 */
	public long stopMaxFunEvals = Long.MAX_VALUE; // it is not straight forward
													// to set a dimension
													// dependent
													// default as the user can
													// first set stopMaxFunEvals
													// and afterwards the
													// dimension
	/** stop if the number of iterations (generations) exceed stopMaxIter */
	public long stopMaxIter = Long.MAX_VALUE;
	/** if true stopping message "Manual:..." is generated */
	public boolean stopnow = false;

	/**
	 * flag used by methods iterate(), whether to write output to files. Methods
	 * write an output file if flgWriteFile&#62;0.
	 */

	/**
	 * determines whether CMA says hello after initialization.
	 * */
	public int verbosity = 1;
	/** Output files written will have the names outputFileNamesPrefix*.dat */
	public String outputFileNamesPrefix = "outcmaes";
	/**
	 * if chosen > 0 the console output from functions <code>print...</code> is
	 * saved additionally into a file, by default <tt>outcmaesdisp.dat</tt>
	 */
	public int writeDisplayToFile = 1;

	/**
	 * only for >= 1 results are always exactly reproducible, as otherwise the
	 * update of the eigensystem is conducted depending on time measurements,
	 * defaut is 0.2
	 */
	public double maxTimeFractionForEigendecomposition = 0.2;
	/**
	 * default is 0.1
	 */
	public double maxTimeFractionForWriteToDefaultFiles = 0.1;

	/**
	 * checks eigendecomposition mainly for debugging purpose, default is
	 * 0==no-check; the function checkEigenSystem requires O(N^3) operations.
	 */
	public int checkEigenSystem = 0;

}
